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ABOUT THIS CHAPTER 


This chapter tells you how to accomplish low-level communication with peripheral 
devices that are connected to the Apple Desktop Bus (ADB). 


Reader's guide: The standard mouse and keyboard drivers automatically take 
care of all required ADB access functions. When the user 
manipulates the mouse or keyboard, the system calls the 
appropriate driver and the application never uses the ADB 
Manager. Hence you need the information in this chapter only 
if you are writing a special driver, such as a driver for a 
new user-input device. 


The ADB is a simple local-area network that connects low-speed input-only 
devices to the operating system. In the Macintosh II and Macintosh SE computers, 
the ADB is used to communicate with one or more keyboards, the mouse, and other 
user input devices. 


Keys located on multiple keyboards are distinguished by the keyboard event 
message, as described in the Toolbox Event Manager chapter. 


Note: An ADB, using the same operating protocols, is also part of the 
Apple IIgs computer. 


This chapter contains three principal sections: 


a description of the Apple Desktop Bus and how it works 

a description of the ADB Manager. This section of system ROM contains 

the routines that a driver must use to access devices connected to the ADB. 
* a discussion of the special requirements for drivers that support 

devices connected to the ADB 


ee 


You should already be familiar with 


« the hardware interface to the Apple Desktop Bus, described in the 
Macintosh Family Hardware Reference 

* events generated by ADB keyboard devices (described in the Toolbox 
Event Manager chapter) if your driver communicates with one or more 
keyboards 
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ABOUT THE APPLE DESKTOP BUS 


The Apple Desktop Bus connects up to 16 low-speed input-only devices to the 
Macintosh II or Macintosh SE computer. Each device can maintain up to four 
variable-size registers, whose contents can be read from or written to by the 
ADB network. Each register may contain from two to eight bytes. Two of the 
device registers have an assigned meaning and a standardized format: register 0, 
used for interrupt information, and register 3, containing the device's 
identification number. The other two device registers have no assigned meaning, 
and may have different meanings for read and write operations. 


The system communicates with the Apple Desktop Bus through the system's 
Versatile Interface Adapter chip (VIA). The VIA is described in the Macintosh 
Hardware chapter. 


Warning: The ADB does not support connecting a device while the computer 
is running. The result may be to reinitialize all devices on the 
bus without informing the system. 


The system always controls the bus. It issues commands to specific devices on 
the bus and they respond by accepting data, sending data, or changing their 
configuration. These commands are discussed below. 


Note: Devices connected to the ADB contain their own single-chip 
microprocessors, which handle both device routines and the 
ADB interface. If the system sends commands to a device with 
a duty cycle of more than 50%, the device's microprocessor 
may become overloaded. 


Bus Commands 


Each bus command consists of a byte that the system sends to a device connected 
to the ADB. Applications may place bus commands on the network by calling the 
routine ADBOp, discussed under "ADB Manager Routines" later in this chapter. 
There are four bus commands; their bit layouts are shown in Figure 1. All other 
bit layouts are reserved. 
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Figure 1-ADEB Command Formats 


Figure 1—ADB Command Formats 
The individual commands are discussed below. 


Warning: Values of the low bytes of the ADB command formats other than 
those shown in Figure 1 are reserved, and should not be used. 


SendReset 


The SendReset command forces a hardware reset of all devices connected to the 
ADB. Such a reset clears all pending device actions and places the devices in 
their startup state. All devices are able to accept new ADB commands and user 
inputs immediately thereafter. All devices ignore the high-order four bits of 
the SendReset command. 


Flush 


The Flush command flushes data from the single device specified by the network 
address in its high-order four bits. Network addresses are discussed below, 
under "Device Addressing". It purges any pending user inputs and make the device 
ready to accept new commands and input data. 


Listen 

The Listen command is used to send instructions to devices connected to the ADB. 
It transfers data from a buffer in system RAM to a register in the device 
specified by the network address in its high-order four bits. The device 
register is specified by the low-order two bits of the Listen command. 


Talk 
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The Talk command is used to fetch user inputs from devices connected to the ADB. 
It is the complement of the Listen command. It transfers data from a register in 
the device specified by the network address in its high-order four bits to a 
buffer in system RAM. The device register is specified by the low-order two bits 
of the Talk command. 


Device Registers 


Each device connected to the ADB contains four registers, each of which may 
store from two to eight bytes of data. Each register is identified by the value 
of the low-order two bits in a Listen or Talk command. Registers 0 and 3 have 
dedicated functions; registers 1 and 2 are used for purposes specific to each 
device, and need not be present in a device. 


Note: ADB device registers are virtual registers; they need not be 
implemented physically. The device firmware must only respond 
to register commands as if a register were present. 


Register 0 


Device register 0 is reserved for input data. If the device has user-input data 
to be fetched, it places the data in register 0 and requests service. It 
continues to request service until the system retrieves its data. The system 
responds to data-input requests with the following polling sequence: 


e It generates a Talk command for register 0 in each device connected 
to the ADB. 

e If the device has data to send, it responds. The system does not 
poll the next device until the data is exhausted. 

e If the device has no data to send, or if its data is exhausted, the 
VIA generates an interrupt. The system then polls the next device. 

e This process continues until no devices request service. 


Register 3 
Device register 3 is reserved for device identification data and operating 
flags. Application programs may set this data with Listen commands and read it 


with Talk commands. Register 3 stores 16 bits, divided into the fields shown in 
Figure 2. 


i413 1211109 3 ? 


Foes 


Reserved 
Bernice Request Enable 
Exceptional Event 


Figure 2—Fommat of Device Register 3 


Figure 2—Format of Device Register 3 
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Except for commands that contain certain reserved device handler ID values 
(listed below), every command to register 3 changes the entire register 
contents. Hence to change part of the register, you should first fetch its 
current contents with a Talk command and then send it an updated value with 
Listen. You can change part of the contents of register 3 by using special 
device handler ID values, as described below. 


The device handler ID field indicates the device's type. With certain devices, 
an application can change the device's mode of operation by sending it a new ID 
value. If the device supports the new mode, it stores the new value in this 
field. 


Warning: You are assigned handler IDs by Apple Software Licensing, so 
they do not conflict with the values of other devices that may 
be connected to the ADB at the same time. 


When certain reserved values are sent to the device handler ID field by a Listen 
command, they are not stored in the field; instead, they cause specific device 
actions. Hence these values cannot be used as device ID values. They are the 
following: 


Value Action 


$00 Change bits 8-13 of register 3 to match the rest of the command; 
leave Device Handler ID value unchanged. 

$FD Change Device Address to match bits 8-11 if the device activator 
has been depressed; leave Device Handler ID value and flags unchanged. 

$FE Change Device Address to match bits 8-11 if the result produces no 
address duplication on the bus; leave Device Handler ID value and 
flags unchanged. 

$FF Initiate device self-test. If self-test succeeds, leave register 3 
unchanged; if self-test fails, clear Device Handler ID field to $00. 


Other Device Handler ID values may be stored in the field. 
Note: Device Handler ID values below $20 are reserved by Apple. 


The Device Address field indicates the device's location within the 16 possible 
device locations of the ADB. An application may change its value with a Listen 
command. When this field is interrogated with a Talk command, it returns a 
random value. This helps you separate multiple devices that have the same ADB 
address; for further information, see "Device Addressing", below. 


The Service Request Enable bit is set by the device to request an interrupt 
poll. 


Device Addressing 


There are 16 possible direct addresses, $00-$0F, for devices connected to the 
ADB. However, it is possible to connect more than one device to an address; this 
might happen, for example, in a system with two alternate keyboards. 
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When several devices share a single ADB address, but there are free addresses 
available in the net, the system will automatically reassign addresses until 
they are all different. It will do this every time the ADB Manager is 
initialized or reinitialized. To find out a device's new address, use the calls 
GetIndADB or GetADBInfo, described later in this chapter. 


Standard ADB Device Drivers 
The Macintosh II and Macintosh SE systems contain two standard ADB drivers: 


e the mouse driver, which supports the ADB mouse. The Apple mouse 
has an original ADB address of 3. 

¢ the universal keyboard driver, which supports all Apple ADB keyboards. 
The Apple keyboard has an original ADB address of 2, with a Device 
Handler ID of 1 for the Macintosh II keyboard and 2 for the Apple 
Extended Keyboard. These keyboards are described in the Toolbox 
Event Manager chapter. 


These drivers reside in the system ROM. In addition, ADB address 0 is reserved 
for the ADB chip itself. You can change the ADB addresses of the mouse or 
keyboard, as described above under "Device Registers," but Apple does not 
recommend doing so. 


Assembly-language note: The ADB address of the keyboard on which the 
last-typed character was entered is now stored 
in the global variable KbdLast. The type of the 
keyboard on which the last-typed character was 
entered is stored in the global variable KbdType. 
The value of KbdType is the Device Handler ID 
value in Register 3 of the device; values below 
$20 are reserved by Apple. 


The requirements for writing new ADB device drivers are discussed later in this 
chapter. 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE APPLE DESKTOP BUS ¢ 7 of 15 


ADB MANAGER ROUTINES 


The ADB Manager consists of six routines located in the 256K ROM. You would use 
them only if you needed to access bus devices directly or communicate with a 
special device. 


Some of these routines access and update information in the ADB device table, a 
structure placed in the system heap by ROM code during system startup. It lists 
for each device the device's type, its original ADB address, its current ADB 
address, the address of the routine that services the device, and the address of 
the area in RAM used for temporary data storage by its driver. The ADB device 
table is accessible only through ADB Manager routines. 


PROCEDURE ADBReInit; 
Trap macro _ADBReInit 


ADBReInit reinitializes the entire Apple Desktop Bus. It clears the ADB device 
table to zeros and places a SendReset command on the bus to reset all devices to 
their original addresses. ADBReInit has no parameters. 


Because it does not deallocate ADB resources on the system heap, ADBReInit 
should not be used for routine bus initialization. Apple strongly recommends 
against adding devices while the system is running; therefore, you should never 
call ADBReInit. 


ADBReInit also calls a routine pointed to by the low memory global JADBProc 

at the beginning and end of its execution. You can insert your own 
preprocessing/postprocessing routine by changing the value of JADBProc; 
ADBReInit conditions it by setting DO to © for preprocessing and to 1 for 
postprocessing. Your procedure must restore the value of DO and branch to the 
Original value of JADBProc on exit. JADBProc should be used to de-allocate 
memory used by the driver (see MacDTS Sample Code "TbltDrvr" for an example), 
and then it should chain to the procedure originally found in JADBProc. 


The complete ADBReInit sequence is therefore the following: 
JSR to JADBProc with DO set to 0 
reinitialize the Apple Desktop Bus 


clear the ADB device table 
JSR to JADBProc with DO set to 1 


FUNCTION ADBOp (data: Ptr; compRout: ProcPtr; buffer: Ptr; 
commandNum: INTEGER) : OSErr; 


Trap macro _ADBOp 


On entry: AQ: pointer to parameter block 
DO: commandNum (byte) 


Parameter block 
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--> 0 buffer pointer 


--> 4 compRout pointer 
ae 8 data pointer 
On exit: DO: result code (byte) 


The completion routine pointed to by compRout will be passed the following 
parameters on entry: 


DO: commandNum (byte) 

AQ: pointer to buffer, data stored as a Pascal string (maximum 
8 bytes data preceded by one length byte) 

Al: pointer to completion routine (compRout) 

A2: pointer to optional data area (data) 


ADBOp transmits over the bus the command byte whose value is given by 
commandNum. The structure of the command byte is given earlier in Figure 1. 
ADBOp executes only when the ADB is otherwise idle; otherwise it is held ina 
command queue. It returns an error if the command queue is full. The length of 
the data buffer pointed to by buffer is contained in its first byte, like a 
Pascal string. The optional data area pointed to by data is for local storage by 
the completion routine pointed to by compRout. ADBop should be used sparingly; 
it is not intended for polling a device. The host automatically polls devices 
with data to deliver. 


Result codes noErr No error 
-1 Unsuccessful completion 


FUNCTION CountADBs: INTEGER; 

Trap macro _CountADBs 

On exit: DO: number of devices (byte) 

CountADBs returns a value representing the number of devices connected to the 
ADB by counting the number of entries in the device table. It has no arguments 


and returns no error codes. 


FUNCTION GetIndADB (VAR info: ADBDataBlock; 
devTableIndex: INTEGER) : ADBAddress; 


Trap macro _GetIndADB 


On entry: AQ: pointer to parameter block 
DO: entry index number; range = 1..CountADBs (byte) 


Parameter block 


<-- 0 device type byte (handler ID) 
<-- 1 Original ADB address byte 
<-- 2 service routine address pointer (compRout) 
<-- 6 data area address pointer (data) 

On exit: DO: positive value: current ADB address (byte) 


negative value: error code (byte) 
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GetIndADB returns information from the ADB device table entry whose index number 
is given by devTableIndex. ADBDataBlock has this form: 


TYPE ADBDataBlock = 
PACKED RECORD 


devType: SignedByte; {device type (handler ID)} 
origADBAddr: SignedByte; {original ADB address} 
dbServiceRtPtr: Ptr; {service routine address (compRout) } 
dbDataAreaAddr: Ptr {data area address (data)} 

END; 


GetIndADB returns the current ADB address of the device. If it is unable to 
complete execution successfully, GetIndADB returns a negative value. 


FUNCTION GetADBInfo (VAR info: ADBDataBlock; ADBAddr: ADBAddress) : OsErr; 
Trap macro _GetADBInfo 


On entry: AQ: pointer to parameter block 
DO: ADB address of the device (byte) 


Parameter block 


<-- 0 device handler ID byte 
<-- 1 original ADB address byte 
<-- 2 service routine address pointer (compRout) 
<-- 6 data area address pointer (data) 
On exit: DO: result code (byte) 


GetADBInfo returns information from the ADB device table entry of the device 
whose ADB address is given by ABDAddr. The structure of ADBDataBlock is given 
above under "GetIndADB". 

Result codes noErr No error 

FUNCTION SetADBInfo (VAR info: ADBSetInfoBlock; ADBAddr: ADBAddress) : OsErr; 
Trap macro _SetADBInfo 


On entry: AQ: pointer to parameter block 
DO: ADB address of the device (byte) 


Parameter block 


--> 0 service routine address pointer (compRout) 
--> 4 data area address pointer (data) 
On exit: DO: result code (byte) 


SetADBInfo sets the service routine address and the data area address in the ADB 
device table entry for the device whose ADB address is given by ABDAddr. 
ADBSetInfoBlock has this form: 


TYPE ADBSetInfoBlock = 
RECORD 
siServiceRtPtr: Ptr; {service routine address (compRout) } 
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siDataAreaAddr: Ptr {data area address (data) } 
END; 


Result codes noErr No error 
Warning: You should send a Flush command to the device after calling it 


with SetADBInfo, to prevent it sending old data to the new data 
area address. 
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WRITING ADB DEVICE DRIVERS 


Drivers for devices connected to the ADB have the following special 
requirements: 


¢ Each ADB device driver must reside in a resource of type 'ADBS'. 
(An example 'ADBS' resource is available in MacDTS Sample Code 
"ToltDrvr.") This type has two sections: initialization and driver code. 
¢ The initialization section of each ADB device driver must support the 
installation procedure described below. 


When the system calls an ADB device driver, it passes it the following values: 


e Register AO points to the data buffer, which is formatted as a 
Pascal string (buffer). 

e Register Al points to the driver's completion routine (compRout) . 

e Register A2 points to the optional data area (data). 

e Register DO contains the ADB command that resulted in the driver 
being called (commandNum) . 


The ADB driver should handle the ADB command passed to it and store any 
resulting input data by an appropriate action, such as by posting an event or 
moving the cursor. 


Note: Events posted from keyboards connected to the ADB now have an 
expanded structure. For more information, see the Toolbox Event 
Manager chapter. 


Installing an ADB Driver 


The Start Manager (described in this volume) finds all the ADB devices connected 
to the system and places their device types and ADB addresses in the ADB device 
table. It then calls the initialization section of each ADB device driver by 
executing the initialization code in its 'ADBS' resource. 


As a minimum, the initialization section of each ADB device driver must do the 
following: 


¢ The driver must allocate all the memory required by the driver code 
in one or more nonrelocatable blocks in the system heap area. 
¢ The driver must install its own preprocessing/postprocessing routine 
(if any) as described above under "ADBReInit". 
e Finally, the driver must initialize the service routine address and 
data area address of its entry in the ADB device table, using SetADBInfo. 
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SUMMARY OF THE ADB MANAGER 


Data Types 
TYPE 
ADBDataBlock = 
PACKED RECORD 
devType: SignedByte; {Handler ID} 
origADBAddr: SignedByte; {original ADB address} 
dbServiceRtPtr: Ptr; {service routine address (compRout) } 
dbDataAreaAddr: Ptr {data area address (area)} 
END; 
ADBSetInfoBlock = 
RECORD 
siServiceRtPtr: Ptr; {service routine address} 
siDataAreaAddr: Ptr {data area address} 
END; 
Routines 


Initializing the ADB Manager 
PROCEDURE ADBReInit; 
Communicating Through the ADB 


FUNCTION ADBOp (data: Ptr; compRout: ProcPtr; buffer: Ptr; 
commandNum: INTEGER) : OSErr; 


Getting ADB Device Information 
FUNCTION CountADBs: INTEGER; 
FUNCTION GetIndADB (VAR info: ADBDataBlock; 
devTableIndex: INTEGER) : ADBAddress; 
FUNCTION GetADBInfo (VAR info: ADBDataBlock; ADBAddr: ADBAddress) : OsErr; 
Setting ADB Device Information 


FUNCTION SetADBInfo (VAR info: ADBSetInfoBlock; ADBAddr: ADBAddress) : OsErr; 


Assembly-Language Information 


Variables 
JADBProc Pointer to ADBReInit preprocessing/postprocessing routine 
KbdLast ADB address of the keyboard last used (byte) 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE APPLE DESKTOP BUS « 13 of 15 


KbdType Keyboard type of the keyboard last used (byte) 


Routines 
Trap macro On entry On Exit 
_ADBReInit 
_ADBOp AQ: pointer to parameter block DO: result code (byte) 
buffer (pointer) 
compRout (pointer) 
data (pointer) 
DO: commandNum (byte) 
_CountADBs DO: result code (byte) 
_GetIndADB AQ: pointer to parameter block DO: positive value: 
device type (byte) current ADB 
Original ADB address (byte) address (byte) 
service routine address (pointer) negative value: 
data area address (pointer) error code (byte) 
DO: entry index number; 
range = 1..CountADBs (byte) 
_GetADBInfo AQ: pointer to parameter block DO: result code (byte) 
device handler ID (byte) 
original ADB address (byte) 
service routine address (pointer) 
data area address (pointer) 
DO: current ADB address of the device (byte) 
_SetADBInfo AQ: pointer to parameter block DO: result code (byte) 


service routine address (pointer) 
data area address (pointer) 
DO: current ADB address of the device (byte) 
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Further Reference: 


Toolbox Event Manager 
Technical Note #143, Don't Call ADBReInit on the SE with System 4.1 


Technical Note #160, Key Mapping 
Technical Note #206, Space Aliens Ate My Mouse 
"Macintosh Family Hardware Reference" 


END OF DOCUMENT 
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